/*
Copyright 2011 Johan Maasing

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 */
package nu.zoom.catonine.fontchooser;

import java.awt.Font;

import javax.swing.JComponent;

import nu.zoom.catonine.stylerule.ChangeTracker;
import nu.zoom.swing.desktop.worker.EventQueuePolicy;
import nu.zoom.swing.desktop.worker.Policy;
import nu.zoom.ui.Resources.ResourceNotFoundException;

/**
 * @author "Johan Maasing" &lt;johan@zoom.nu&gt;
 * 
 */
public interface FontChooser extends ChangeTracker {
	/**
	 * Callback from the FontChooser when the user modifies attributes on the
	 * font selection. Notice that the callback is not guaranteed to be on the
	 * Swing EventQueue thread.
	 * 
	 * @author "Johan Maasing" &lt;johan@zoom.nu&gt;
	 * 
	 */
	public interface FontValuesListener {
		/**
		 * The user changed an attribute of the selected font.
		 * 
		 * @param source
		 *            The font chooser the user edited.
		 * @param font
		 *            The new font matching the user selected values. Might be
		 *            null if the user de-selected a font choice (and wants to
		 *            use 'default').
		 */
		public void fontValuesChanged(FontChooser source, Font font);
	}

	/**
	 * Add a listener for user changes to the font.
	 * 
	 * @param listener
	 */
	public void addFontValuesListener(FontValuesListener listener);

	/**
	 * Remove a previously registered listener.
	 * 
	 * @param listener
	 */
	public void removeFontValuesListener(FontValuesListener listener);

	/**
	 * Get the current font attributes.
	 * 
	 * @return The current font settings the suer has selected. Notice that the
	 *         font might be a default font and the user has made no active
	 *         selection. Use the changetracker if you need to know if the user
	 *         has made any changes.
	 * @see ChangeTracker#isChanged()
	 */
	public Font getCurrentFontValues();

	/**
	 * Get the GUI component where the user can specify font values. If multiple
	 * calls are made to this method the same Swing component might be returned.
	 * In other words, do not change the component, only display it.
	 * 
	 * @param startFont
	 *            The font to initalize the panel with. May be null in which
	 *            case the panel will initialize with empty fields and default
	 *            values.
	 * @param defaultFont
	 *            The font to use if the user de-selects fonts and wants to use
	 *            the default font.
	 * @return A component that the user can use to set values for the font.
	 * @throws ResourceNotFoundException
	 */
	@EventQueuePolicy(Policy.EVENT_QUEUE)
	public JComponent getFontChooserGUI(Font startFont, Font defaultFont) throws ResourceNotFoundException;
}
